home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_400 / 400_01 / socketpp-1.5 / socket++.info-2 < prev    next >
Encoding:
GNU Info File  |  1993-11-06  |  20.7 KB  |  530 lines
  1. This is Info file socket++.info, produced by Makeinfo-1.49 from the
  2. input file socket++.texi.
  3.  
  4.    This info file describes the C++ family of socket classes.
  5.  
  6.    Copyright (C) 1992,1993 Gnanasekaran Swaminathan <gs4t@virginia.edu>
  7.  
  8.    Permission is granted to make and distribute verbatim copies of this
  9. document provided the copyright notice and this permission notice are
  10. preserved on all copies.
  11.  
  12. 
  13. File: socket++.info,  Node: iosockunix,  Prev: iosockinet,  Up: sockstream Classes
  14.  
  15. iosockunix Classes
  16. ==================
  17.  
  18.    We discuss only `isockunix' here. `osockunix' and `iosockunix' are
  19. similar.
  20.  
  21. isockunix class
  22. ---------------
  23.  
  24.    `isockunix' is used to handle interprocess communication in UNIX
  25. domain. It is derived from `isockstream' class and it uses a
  26. `sockunixbuf' as its stream buffer. *Note iosockstream::, for more
  27. details on `isockstream'. *Note sockunixbuf Class::, for information on
  28. `sockunixbuf'.
  29.  
  30.    In what follows,
  31.    - `ty' is a `sockbuf::type' and must be one of
  32.      `sockbuf::sock_stream', `sockbuf::sock_dgram',
  33.      `sockbuf::sock_raw', `sockbuf::sock_rdm', and
  34.      `sockbuf::sock_seqpacket'
  35.  
  36.    - `proto' denotes the protocol number and is of type int
  37.  
  38.    - `sb' is a `sockbuf' object and must be in UNIX domain
  39.  
  40.    - `sinp' is a pointer to an object of `sockunixbuf'
  41.  
  42. `isockunix is (ty, proto)'
  43.      constructs an `isockunix' object `is' whose `sockunixbuf' buffer
  44.      is of the type `ty' and has the protocol number `proto'. The
  45.      default protocol number is 0.
  46.  
  47. `isockunix is (sb)'
  48.      constructs a `isockunix' object `is' whose `sockunixbuf' is `sb'.
  49.      `sb' must be in UNIX domain.
  50.  
  51. `isockunix is (sinp)'
  52.      constructs a `isockunix' object `is' whose `sockunixbuf' is `sinp'.
  53.  
  54. `sinp = is.rdbuf ()'
  55.      returns a pointer to the `sockunixbuf' of `isockunix' object `is'.
  56.  
  57. `isockunix::operator ->'
  58.      returns `sockunixbuf' of `sockunix' so that the `sockunix' object
  59.      acts as a smart pointer to `sockunixbuf'.
  60.  
  61.                   is->localhost (); // same as is.rdbuf ()->localhost ();
  62.  
  63. iosockunix examples
  64. -------------------
  65.  
  66.    `tsunread' listens for connections. When `tsunwrite' requests
  67. connection, `tsunread' accepts it and waits for input. `tsunwrite'
  68. sends the string "Hello!!!" to `tsunread'. `tsunread' reads the string
  69. sent by `tsunwrite' and prints on its stdout.
  70.  
  71.      // tsunread.cc
  72.      #include <sockunix.h>
  73.      extern "C" int unlink (const char*);
  74.      main ()
  75.      {
  76.          sockunixbuf sunb (sockbuf::sock_stream);
  77.          unlink ("/tmp/socket+-");
  78.          sockunixaddr suna ("/tmp/socket+-");
  79.          sunb.bind (suna);
  80.          sunb.listen (2);
  81.          isockunix is = sunb.accept ();
  82.          char buf[32];
  83.          is >> buf; cout << buf << endl;
  84.      }
  85.  
  86.      // tsunwrite.cc
  87.      #include <sockunix.h>
  88.      main ()
  89.      {
  90.          osockunix os (sockbuf::sock_stream);
  91.          sockunixaddr suna ("/tmp/socket++");
  92.          os->connect (suna);
  93.          os << "Hello!!!\n";
  94.      }
  95.  
  96. 
  97. File: socket++.info,  Node: pipestream Classes,  Next: Error Handling,  Prev: sockstream Classes,  Up: Top
  98.  
  99. pipestream Classes
  100. ******************
  101.  
  102.    `pipestream' stream classes provide the services of the UNIX system
  103. calls `pipe' and `socketpair' and the C library function `popen'.
  104. `ipipestream', `opipestream', and `iopipestream' are obtained by simply
  105. deriving from `isockstream', `osockstream' and `iosockstream'
  106. respectively. *Note sockstream Classes:: for details.
  107.  
  108.    In what follows,
  109.    - `ip' is an `ipipestream' object
  110.  
  111.    - `op' is an `opipestream' object
  112.  
  113.    - `iop' is an `iopipestream' object
  114.  
  115.    - `cmd' is a char* denoting an executable like "wc"
  116.  
  117.    - `ty' is of type `sockbuf::type' indicating the type of the
  118.      connection
  119.  
  120.    - `proto' is an `int' denoting a protocol number
  121.  
  122. `ipipestream ip(cmd)'
  123.      construct an `ipipestream' object `ip' such that the output of the
  124.      command `cmd' is available as input through `ip'.
  125.  
  126. `opipestream op(cmd)'
  127.      construct an `opipestream' object `op' such that the input for the
  128.      command `cmd' can be send through `op'.
  129.  
  130. `iopipestream iop(cmd)'
  131.      construct an `iopipestream' object `iop' such that the input and
  132.      the output to the command `cmd' can be sent and received through
  133.      `iop'.
  134.  
  135. `iopipestream iop(ty, proto)'
  136.      construct a `iopipestream' object `iop' whose socket is a
  137.      socketpair of type `ty' with protocol number `proto'. `ty'
  138.      defaults to `sockbuf::sock_stream' and `proto' defaults to 0.
  139.      Object `iop' can be used either as a `pipe' or as a `socketpair'.
  140.  
  141. `iop.pid ()'
  142.      return the process id of the child if the current process is the
  143.      parent or return 0. If the process has not forked yet, return -1.
  144.  
  145. `iopipestream::fork ()'
  146.      `fork()' is a static function of class `iopipestream'. `fork()'
  147.      forks the current process and appropriately sets the `cpid' field
  148.      of the `iopipestream' objects that have not forked yet.
  149.  
  150. * Menu:
  151.  
  152. * pipe Example::                 How to use pipestream as pipe?
  153. * socketpair Example::           How to use pipestream as socketpair?
  154. * popen Example::                How to use pipestream as popen?
  155.  
  156. 
  157. File: socket++.info,  Node: pipe Example,  Next: socketpair Example,  Up: pipestream Classes
  158.  
  159. pipestream as pipe
  160. ==================
  161.  
  162.    `pipe' is used to communicate between parent and child processes in
  163. the UNIX domain.
  164.  
  165.    The following example illustrates how to use `iopipestream' class as
  166. a `pipe'. The parent sends the string "I am the parent" to the child
  167. and receives the string "I am the child" from child. The child, in
  168. turn, receives the string "I am the parent" from parent and sends the
  169. string "I am the child" to the parent. Note the same `iopipestream'
  170. object is used for input and output in each process.
  171.  
  172.      #include <pipestream.h>
  173.      
  174.      main()
  175.      {
  176.              iopipestream p;
  177.              if ( p.fork() ) {
  178.                      char buf[128];
  179.                      p << "I am the parent\n";
  180.                      cout << "parent: ";
  181.                      while(p >> buf)
  182.                              cout << buf << ' ';
  183.                      cout << endl;
  184.              }else {
  185.                      char buf[128];
  186.                      p.getline(buf, 127);
  187.                      cout << "child: " << buf << endl;
  188.                      p << "I am the child\n";
  189.              }
  190.      }
  191.  
  192. 
  193. File: socket++.info,  Node: socketpair Example,  Next: popen Example,  Prev: pipe Example,  Up: pipestream Classes
  194.  
  195. pipestream as socketpair
  196. ========================
  197.  
  198.    Like pipes, socketpairs also allow communication between parent and
  199. child processes. But socketpairs are more flexible than pipes in the
  200. sense that they let the users choose the socket type and protocol.
  201.  
  202.    The following example illustrates the use of `iopipestream' class as
  203. a `socketpair' whose type is `sockbuf::sock_dgram'. The parent sends
  204. the string "I am the parent" to the child and receives the string "I am
  205. the child" from the child. The child, in turn, receives and sends the
  206. strings "I am the parent" and "I am the child" respectively from and to
  207. the parent. Note in the following example that the same `iopipestream'
  208. object is used for both the input and the output in each process.
  209.  
  210.      #include <pipestream.h>
  211.      
  212.      main()
  213.      {
  214.              iopipestream p(sockbuf::sock_dgram);
  215.              if ( iopipestream::fork() ) {
  216.                      char buf[128];
  217.                      p << "I am the parent\n";
  218.                      p.getline(buf, 127);
  219.                      cout << "parent: " << buf << endl;
  220.              }else {
  221.                      char buf[128];
  222.                      p.getline(buf, 127);
  223.                      cout << "child: " << buf << endl;
  224.                      p << "I am the child\n";
  225.              }
  226.      }
  227.  
  228. 
  229. File: socket++.info,  Node: popen Example,  Prev: socketpair Example,  Up: pipestream Classes
  230.  
  231. pipestream as popen
  232. ===================
  233.  
  234.    `popen' is used to call an executable and send inputs and outputs to
  235. that executable. For example, the following function executes
  236. "/bin/date", gets its output, and prints it to stdout.
  237.  
  238.      #include <pipestream.h>
  239.      
  240.      main ()
  241.      {
  242.          char buf[128];
  243.          ipipestream p("/bin/date");
  244.      
  245.          p.getline (buf, 127);
  246.          cout << buf << endl;
  247.      }
  248.  
  249.    Here is an example that prints "Hello World!!" on stdout. It uses
  250. `opipestream' object.
  251.  
  252.      #include <pipestream.h>
  253.      
  254.      main ()
  255.      {
  256.          opipestream p("/bin/cat");
  257.          p << "Hello World!!\n";
  258.      }
  259.  
  260.    The following example illustrates the use of `iopipestream' for both
  261. input and output.
  262.  
  263.      #include <pipestream.h>
  264.      
  265.      main()
  266.      {
  267.              char buf[128];
  268.              iopipestream p("lpc");
  269.              p << "help\nquit\n";
  270.              while ( p.getline(buf, 127) ) cout << buf << endl;
  271.      }
  272.  
  273. 
  274. File: socket++.info,  Node: Error Handling,  Next: Pitfalls,  Prev: pipestream Classes,  Up: Top
  275.  
  276. Error Handling
  277. **************
  278.  
  279.    Each class in the Socket++ library uses `error(const char*)' member
  280. function to report any errors that may occur during a system call. It
  281. first calls `perror()' to report the error message for the `errno' set
  282. by the system call. It then calls `(*lib_error_handler) (const char*
  283. nm, const char* errmsg)' where nm is the name of the class.
  284.  
  285.    If the user wants to handle the error more gracefully he can define
  286. his own error handler instead of the default `lib_error_handler'.
  287.  
  288.    In what follows,
  289.    - `eh' is of type void (*)(const char*, const char*)
  290.  
  291. `set_lib_error_handler(eh)'
  292.      returns the old lib error handler after setting `lib_error_handler'
  293.      to eh. This function is part of `libg++' library and is not part
  294.      of Socket++ library.
  295.  
  296. 
  297. File: socket++.info,  Node: Pitfalls,  Next: Index,  Prev: Error Handling,  Up: Top
  298.  
  299. Pitfalls
  300. ********
  301.  
  302.    Deadlocks in datagram sockets are the most common mistakes that
  303. novices make. To alleviate the problem, `sockbuf' class provides timeout
  304. facilities that can be used effectively to avoid deadlocks.
  305.  
  306.    Consider the following simple tsmtp example which sends the HELP
  307. command to a smtp server and gets back the help message. Suppose it
  308. does not know the size of the help message nor the format of the
  309. message. In such cases, the timeout facilities of `sockbuf' class
  310. provides the required tools.
  311.  
  312.    The example terminates the help message reception if the there is no
  313. input activity from the smtp server for 10 seconds.
  314.  
  315. tsmtp.cc
  316. --------
  317.  
  318.      #include <sockinet.h>
  319.      
  320.      main()
  321.      {
  322.          sockinetaddr sina("kelvin.seas.virginia.edu", "smtp", "tcp");
  323.          iosockinet   sio(sockbuf::sock_stream);
  324.      
  325.          sio->connect(sina);
  326.      
  327.          char buf[512];
  328.          sio.getline(buf, 511); cout << buf << endl;
  329.          sio << "HELO kelvin\n";
  330.          sio.getline(buf, 511); cout << buf << endl;
  331.      
  332.          sio << "HELP\n";
  333.      
  334.              // set the receive timeout to 10 seconds
  335.              int tmo = sio->recvtimeout(10);
  336.      
  337.          while ( sio.getline(buf, 511) ) cout << buf << endl;
  338.              // if the above while loop terminated due to timeout
  339.              // clear the state of sio.
  340.          if ( !sio->is_eof() )
  341.              sio.clear();
  342.          sio->recvtimeout(tmo); // reset the receive timeout time
  343.      
  344.          sio << "QUIT\n";
  345.          sio.getline(buf, 511); cout << buf << endl;
  346.      }
  347.  
  348. 
  349. File: socket++.info,  Node: Index,  Prev: Pitfalls,  Up: Top
  350.  
  351. Index
  352. *****
  353.  
  354. * Menu:
  355.  
  356. * accepting connections:                Connection Establishment.
  357. * acknowledgments:                      Acknowledgments.
  358. * base address class:                   sockAddr Class.
  359. * binding addresses:                    Connection Establishment.
  360. * class isockinet:                      iosockinet.
  361. * class isockunix:                      iosockunix.
  362. * class sockbuf:                        sockbuf Class.
  363. * common mistakes:                      Pitfalls.
  364. * connect:                              Connection Establishment.
  365. * connection establishment:             Connection Establishment.
  366. * Copyright:                            Copying.
  367. * copyright notice:                     Copying.
  368. * datagram inet:                        Datagram INET.
  369. * datagram unix:                        Datagram UNIX.
  370. * error handling:                       Error Handling.
  371. * flushing output:                      Reading and Writing.
  372. * getpeername (see sockinetbuf::peeraddr): Methods sockinetbuf.
  373. * getsockname (see sockinetbuf::localaddr): Methods sockinetbuf.
  374. * getsockopt:                           Socket Options.
  375. * inet address class:                   sockinetaddr Class.
  376. * inet domain:                          sockinetbuf Class.
  377. * iopipestream::fork:                   pipestream Classes.
  378. * iopipestream::iopipestream:           pipestream Classes.
  379. * iopipestream::pid:                    pipestream Classes.
  380. * iosockinet examples:                  iosockinet.
  381. * iosockstream class:                   iosockstream.
  382. * iosockstream classes:                 sockstream Classes.
  383. * iosockstream example:                 Stream INET.
  384. * iosockstream::iosockstream:           iosockstream.
  385. * iosockstream::operator->:             iosockstream.
  386. * iosockstream::rdbuf:                  iosockstream.
  387. * iosockunix class:                     iosockunix.
  388. * iosockunix examples:                  iosockunix.
  389. * ipipestream::ipipestream:             pipestream Classes.
  390. * isockinet class:                      iosockinet.
  391. * isockinet::isockinet:                 iosockinet.
  392. * isockinet::operator->:                iosockinet.
  393. * isockinet::rdbuf:                     iosockinet.
  394. * isockstream class:                    iosockstream.
  395. * isockstream example:                  Datagram UNIX.
  396. * isockstream example:                  Datagram INET.
  397. * isockstream::isockstream:             iosockstream.
  398. * isockstream::operator->:              iosockstream.
  399. * isockstream::rdbuf:                   iosockstream.
  400. * isockunix class:                      iosockunix.
  401. * isockunix::isockunix:                 iosockunix.
  402. * isockunix::operator->:                iosockunix.
  403. * isockunix::rdbuf:                     iosockunix.
  404. * listening:                            Connection Establishment.
  405. * names:                                Connection Establishment.
  406. * opipestream::opipestream:             pipestream Classes.
  407. * option getting:                       Socket Options.
  408. * option setting:                       Socket Options.
  409. * osockstream class:                    iosockstream.
  410. * osockstream example:                  Datagram INET.
  411. * osockstream example:                  Datagram UNIX.
  412. * osockstream::operator->:              iosockstream.
  413. * osockstream::osockstream:             iosockstream.
  414. * osockstream::rdbuf:                   iosockstream.
  415. * overview of socket++:                 Overview of Socket++.
  416. * pipe:                                 pipestream Classes.
  417. * pipe example:                         pipe Example.
  418. * pipestream classes:                   pipestream Classes.
  419. * pipestream examples:                  pipestream Classes.
  420. * pitfalls:                             Pitfalls.
  421. * popen:                                pipestream Classes.
  422. * popen example:                        popen Example.
  423. * read timeouts:                        Timeouts.
  424. * setsockopt:                           Socket Options.
  425. * set_lib_error_handler:                Error Handling.
  426. * sockAddr class:                       sockAddr Class.
  427. * sockAddr::family:                     sockAddr Class.
  428. * sockAddr::operator void*:             sockAddr Class.
  429. * sockAddr::size:                       sockAddr Class.
  430. * sockbuf class:                        sockbuf Class.
  431. * sockbuf constructors:                 Constructors.
  432. * sockbuf destructor:                   Destructor.
  433. * sockbuf reading:                      Reading and Writing.
  434. * sockbuf writing:                      Reading and Writing.
  435. * sockbuf::accept:                      Connection Establishment.
  436. * sockbuf::bind:                        Connection Establishment.
  437. * sockbuf::broadcast:                   Socket Options.
  438. * sockbuf::clearerror:                  Socket Options.
  439. * sockbuf::close:                       Destructor.
  440. * sockbuf::connect:                     Connection Establishment.
  441. * sockbuf::debug:                       Socket Options.
  442. * sockbuf::doallocate:                  Reading and Writing.
  443. * sockbuf::dontroute:                   Socket Options.
  444. * sockbuf::flush_output:                Reading and Writing.
  445. * sockbuf::getopt:                      Socket Options.
  446. * sockbuf::gettype:                     Socket Options.
  447. * sockbuf::is_eof:                      Reading and Writing.
  448. * sockbuf::is_exceptionpending:         Reading and Writing.
  449. * sockbuf::is_open:                     Constructors.
  450. * sockbuf::is_open:                     Reading and Writing.
  451. * sockbuf::is_readready:                Reading and Writing.
  452. * sockbuf::is_writeready:               Reading and Writing.
  453. * sockbuf::keepalive:                   Socket Options.
  454. * sockbuf::linger:                      Socket Options.
  455. * sockbuf::listen:                      Connection Establishment.
  456. * sockbuf::msgflag:                     Reading and Writing.
  457. * sockbuf::msgflag:                     Reading and Writing.
  458. * sockbuf::oobinline:                   Socket Options.
  459. * sockbuf::open:                        Constructors.
  460. * sockbuf::operator=:                   Constructors.
  461. * sockbuf::overflow:                    Reading and Writing.
  462. * sockbuf::rcvbuf:                      Socket Options.
  463. * sockbuf::read:                        Reading and Writing.
  464. * sockbuf::recv:                        Reading and Writing.
  465. * sockbuf::recvfrom:                    Reading and Writing.
  466. * sockbuf::recvmsg:                     Reading and Writing.
  467. * sockbuf::recvtimeout:                 Reading and Writing.
  468. * sockbuf::recvtimeout:                 Timeouts.
  469. * sockbuf::reuseaddr:                   Socket Options.
  470. * sockbuf::send:                        Reading and Writing.
  471. * sockbuf::sendmsg:                     Reading and Writing.
  472. * sockbuf::sendtimeout:                 Reading and Writing.
  473. * sockbuf::sendtimeout:                 Timeouts.
  474. * sockbuf::sendto:                      Reading and Writing.
  475. * sockbuf::setopt:                      Socket Options.
  476. * sockbuf::shutdown:                    Destructor.
  477. * sockbuf::shuthow:                     Destructor.
  478. * sockbuf::sndbuf:                      Socket Options.
  479. * sockbuf::sockbuf:                     Constructors.
  480. * sockbuf::sync:                        Reading and Writing.
  481. * sockbuf::sys_read:                    Reading and Writing.
  482. * sockbuf::sys_write:                   Reading and Writing.
  483. * sockbuf::type:                        Constructors.
  484. * sockbuf::underflow:                   Reading and Writing.
  485. * sockbuf::write:                       Reading and Writing.
  486. * sockbuf::xsputn:                      Reading and Writing.
  487. * sockbuf::~sockbuf:                    Destructor.
  488. * socket options:                       Socket Options.
  489. * socketpair:                           pipestream Classes.
  490. * socketpair example:                   socketpair Example.
  491. * sockinetaddr class:                   sockinetaddr Class.
  492. * sockinetaddr::family:                 sockinetaddr Class.
  493. * sockinetaddr::getport:                sockinetaddr Class.
  494. * sockinetaddr::getthostname:           sockinetaddr Class.
  495. * sockinetaddr::operator void*:         sockinetaddr Class.
  496. * sockinetaddr::size:                   sockinetaddr Class.
  497. * sockinetaddr::sockinetaddr:           sockinetaddr Class.
  498. * sockinetbuf class:                    sockinetbuf Class.
  499. * sockinetbuf dgram example:            Datagram INET.
  500. * sockinetbuf stream example:           Stream INET.
  501. * sockinetbuf::localaddr:               Methods sockinetbuf.
  502. * sockinetbuf::localhost:               Methods sockinetbuf.
  503. * sockinetbuf::localport:               Methods sockinetbuf.
  504. * sockinetbuf::open:                    Methods sockinetbuf.
  505. * sockinetbuf::operator =:              Methods sockinetbuf.
  506. * sockinetbuf::peeraddr:                Methods sockinetbuf.
  507. * sockinetbuf::peerhost:                Methods sockinetbuf.
  508. * sockinetbuf::peerport:                Methods sockinetbuf.
  509. * sockinetbuf::sockinetbuf:             Methods sockinetbuf.
  510. * sockstream classes:                   sockstream Classes.
  511. * sockunixaddr class:                   sockunixaddr Class.
  512. * sockunixaddr::family:                 sockunixaddr Class.
  513. * sockunixaddr::operator void*:         sockunixaddr Class.
  514. * sockunixaddr::size:                   sockunixaddr Class.
  515. * sockunixaddr::sockunixaddr:           sockunixaddr Class.
  516. * sockunixbuf class:                    sockunixbuf Class.
  517. * sockunixbuf datagram example:         Datagram UNIX.
  518. * sockunixbuf::open:                    Methods sockunixbuf.
  519. * sockunixbuf::operator =:              Methods sockunixbuf.
  520. * sockunixbuf::sockunixbuf:             Methods sockunixbuf.
  521. * stream inet:                          Stream INET.
  522. * stream unix:                          Stream UNIX.
  523. * timeout example:                      Pitfalls.
  524. * timeouts:                             Timeouts.
  525. * unix address class:                   sockunixaddr Class.
  526. * unix domain:                          sockunixbuf Class.
  527. * write timeouts:                       Timeouts.
  528.  
  529.  
  530.